<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Shapes" />
		<title>PDF Graphics .NET documentation - Shapes</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Shapes
			</span>
		</div>
		
		<h1>Shapes</h1>

		<p>
			This section covers the following topics:
			<ul>
				<li><a href="#Primitives">Primitives</a></li>
				<li><a href="#Paths">Paths</a></li>
				<li><a href="#Usage">Usage and limitations</a></li>
			</ul>
		</p>
						
		<h2><a name="Primitives"></a>Primitives</h2>
				
		<h3>Line</h3>
		
		<p>
			To draw a line, use the <span class="code">DrawLine()</span> method. The arguments to this method are the X and Y coordinates of the
			start and end point of the line. The line is considered to exist by itself; drawing two lines does not join the lines together.
			To draw shapes composed of multiple lines, see the <a href="#Paths">Paths</a> section below.
		</p>
		
		<div class="sampleCode">g.DrawLine(Rgb.BluePen, 20, 20, 500, 20);</div>
		
		<h3>Rectangle</h3>
		
		<p>
			To draw a rectangle, use the <span class="code">DrawRectangle()</span> method. To fill a rectangle, use <span class="code">FillRectangle()</span>.
			You can either specify the rectangle's position and dimensions separately, or use a <a href="..reference/Rectangle.html">Rectangle</a> value.
		<p>
			
		<div class="sampleCode">g.DrawRectangle(Rgb.BluePen, 20, 20, 100, 50);

g.FillRectangle(Rgb.GreenBrush, new Rectangle( 20, 20, 100, 50));</div>

		<h3>Rounded rectangle</h3>
		
		<p>
			A rounded rectangle is a rectangle with rounded corners. Use the <span class="code">DrawRoundedRectangle()</span>
			and <span class="code">FillRoundedRectangle()</span> methods to draw or fill, respectively. Both methods accept a radius as the
			final argument. The radius determines the size of the roundings.
		<p>
			
		<div class="sampleCode">g.FillRoundedRectangle(Rgb.RedBrush, 20, 20, 100, 50, 3);</div>
		
		<h3>Circles and ellipses</h3>
		
		<p>
			Circles and ellipses are painted with the <span class="code">DrawEllipse()</span> and <span class="code">FillEllipse()</span> methods.
			These methods accept a <span class="code">Rectangle</span> argument that serves as the bounding box of the ellipse.
			To draw or fill a circle, specify a bounding box with equal width and height.
		</p>				
		
		<div class="sampleCode">g.DrawEllipse(Rgb.BluePen, new Rectangle(20, 20, 100, 50));
g.FillEllipse(Rgb.GreenBrush, new Rectangle(200, 20, 80, 80));</div>
		
		<p>
			In the above example, line 1 draws an ellipse outline with a horizontal diameter of 100 points and a vertical diameter of 50 points.
			Line 2 fills a circle with a diameter of 80 points.
		</p>
		
		<p>
			<strong>Note:</strong> The PDF specification does not include ellipses or circles. Instead, PDF Graphics .NET simulates
			these shapes through bezier curves. In practice, the simulation is adequate and ellipses and circles are painted accurately.
		</p>
		
		<h2><a name="Paths"></a>Paths</h2>
		
		<p>
			It is possible to construct more elaborate shapes, including ones that use curves instead of straight lines, using the
			<span class="code">GraphicsPath</span> class. To paint a path, it needs to be defined first. After that, it can be
			drawn or filled.
		</p>
		
		<p>
			To start defining a path, construct an instance of <span class="code">GraphicsPath</span>. Then, use its methods to add
			lines, curves and rectangles. See the example below:
		</p>
		
		<div class="sampleCode">GraphicsPath path = new GraphicsPath();
			
path.AddLine(0, 0, 100, 0); 
path.AddLine(100, 0, 100, 100); 
path.AddLine(100, 100, 50, 150);
path.AddLine(50, 150, 0, 100);
path.Close();

g.DrawPath(Rgb.RedPen, path, 50, 50);</div>

		<p>
			In the example, a path is constructed and three lines added to it. The path is then closed. This will cause a line to be added that
			links the first and last point in the path. The path is then drawn with a red pen. If the shape hadn't been closed, the shape
			would have a gap between the first and last points. Compare the two results below:
		</p>
		
		<img src="../images/Path_Open_Closed.jpg" title="The same path, open and closed" />
			
		<p>
			Open paths have no effect when filling a path with a brush. The resulting shape is the same for an open path and a closed
			one.
		</p>
				
		<p>The <span class="code">GraphicsPath</span> class has methods for adding lines, curves and rectangles.</p>
		
		<p>
			<span class="code">AddLine()</span><br/>
			Adds a line to the path. The end point of this line will be remembered as the path's last point.
			If the start point or end point of the line is the same as the last point in the path, the
			new line is joined to the last point, and the appearance of the join is affected by the pen used to draw the path with
			(see <a href="Colours_pens_brushes.html#LineAppearance">Colours, pens and brushes</a>).
		</p>

		<p>
			<span class="code">AddCurve()</span><br/>
			Adds a cubic bezier curve to the path. The end point of this curve will be remembered as the	path's last point.
			If the start point or end point of the curve is the same as the last point in the path, the
			curve is joined to the last point, and the appearance of the join is affected by the pen used to draw the path with.
		</p>

		<p>
			<span class="code">AddRectangle()</span><br/>
			Adds a rectangle to the path. This resets the path's last point, so that the next line or curve drawn will not be
			joined to the previous last point.
		</p>

		<p>
			<span class="code">AddRoundedRectangle()</span><br/>
			Adds a rounded rectangle to the path. This resets the path's last point, so that the next line or curve drawn will not be
			joined to the previous last point.
		</p>
			
		<h3>Multiple shapes</h3>
		
		<p>
			A single path can contain multiple shapes, each composed of a set of elements. The different shapes are distinguished from
			each other by closing the current set of elements before adding new elements. The <span class="code">GraphicsPath</span>'s
			<span class="code">Close()</span> method doubles as a closing operator and shape separator. Take a look at the following
			example:
		</p>
		
		<div class="sampleCode">GraphicsPath twoShapes = new GraphicsPath();
Rectangle rect = new Rectangle(0, 0, 50, 50);

twoShapes.AddLine( 0, rect.Height / 2f,
                   rect.Width / 2f, 0);
twoShapes.AddLine( rect.Width/2f, 0,
                   rect.Width/2f, rect.Height/4f);
twoShapes.AddLine( rect.Width / 2f, rect.Height / 4f,
                   rect.Width, rect.Height / 4f);
twoShapes.AddLine( rect.Width, rect.Height / 4f,
                   rect.Width, rect.Height * 3 / 4f);
twoShapes.AddLine( rect.Width, rect.Height * 3 / 4f,
                   rect.Width/2f, rect.Height * 3 / 4f);
twoShapes.AddLine( rect.Width / 2f, rect.Height * 3 / 4f,
                   rect.Width / 2f, rect.Height);

twoShapes.Close();
            
rect.Move(rect.Width * 2.2f, 0);
twoShapes.AddLine( rect.Left, rect.Height / 2f,
                   rect.Left - rect.Width / 2f, 0);
twoShapes.AddLine( rect.Left - rect.Width / 2f, 0,
                   rect.Left - rect.Width / 2f, rect.Height / 4f);
twoShapes.AddLine( rect.Left - rect.Width / 2f, rect.Height / 4f,
                   rect.Left - rect.Width, rect.Height / 4f);
twoShapes.AddLine( rect.Left - rect.Width, rect.Height / 4f,
                   rect.Left - rect.Width, rect.Height * 3 / 4f);
twoShapes.AddLine( rect.Left - rect.Width, rect.Height * 3 / 4f,
                   rect.Left - rect.Width / 2f, rect.Height * 3 / 4f);
twoShapes.AddLine( rect.Left - rect.Width / 2f, rect.Height * 3 / 4f,
                   rect.Left - rect.Width / 2f, rect.Height);
twoShapes.Close();

g.DrawPath(redPen, twoShapes, 10, 170);
g.FillPath(YellowBrush, twoShapes, 10, 170);</div>
		
		<p>
			A path is created, and elements are added to it. Because of the <span class="code">Close()</span> statement half-way through,
			the path is composed of two shapes, and the result of painting the path is shown below.
		</p>
		
		<p><img src="../images/Path_with_two_shapes.jpg" title="A path with two shapes" /></p>
						
		<h2><a name="Usage"></a>Usage and limitations</h2>
		
		<p>
			Paths combine a series of lines, curves and other primitives into a single unit that can be drawn or filled with any pen or brush.
			Because no colour information is stored in the path, it can not be used to group a set of graphics together into a reusable
			construct. Instead, see <a href="graphics/Images_stencils.html">Images and stencils</a> for a way to achieve this.
			The main use of paths is defining complex clipping areas - the shape created by a path can be used to 'cut out' an area of the
			page so that the graphics operations performed underneath it show through. See <a href="graphics/Clipping.html">Clipping</a>
			for more details.
		</p>
				
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="Colours_pens_brushes.html">&lt; Colours, pens and brushes</a> | <a href="Text_fonts_styles.html">Text, fonts and text styles &gt;</a>
		
	</body>
	
</html>